home *** CD-ROM | disk | FTP | other *** search
/ Graphics Plus / Graphics Plus.iso / libs / sphigs / sph_dos.lha / dos / readme < prev    next >
Encoding:
Text File  |  1991-11-26  |  12.4 KB  |  291 lines
  1. Copyright 1991, Addison-Wesley Publishing Company, Inc.
  2.  
  3. Addison-Wesley Publishing Company, Inc. makes no representations
  4. or warranties, express or implied, with respect to this software and
  5. its documentation, including without limitations, any implied warranties of
  6. merchantibility or fitness for a particular purpose, all of which are expressly
  7. disclaimed. The exclusion of implied warranties is not permitted by
  8. some states. The above exclusion may not apply to you. This warranty
  9. provides you with specific legal rights. There may be other rights that you
  10. have which may vary from state to state.
  11.  
  12. Adopters of Foley, van Dam, Feiner, and Hughes' Computer Graphics:
  13. Principles and Practice, 2nd edition may copy this software for students
  14. in their classes. The software may not otherwise be reproduced without
  15. the prior written permission of the publishers.
  16.  
  17.  
  18.  ============================================================================
  19.                OVERVIEW OF THE PACKAGES
  20.  
  21. SRGP (Simple Raster Graphics Package) and SPHIGS (Simple Programmer's
  22. Hierarchical Interactive Graphics System) reflect the two major schools of
  23. interactive graphics programming.  SRGP combines features of the Quickdraw and
  24. Xlib 2D integer raster-graphics packages.  SPHIGS provides the fundamental
  25. features of a 3D floating-point package with hierarchical display lists.
  26.  
  27. The packages are designed for instructional use but can be used to implement
  28. significant graphics applications.
  29.  
  30.  
  31. ==============================================================================
  32.                   VERSION INFORMATION
  33.  
  34. Version numbers:
  35.         SRGP:   1.0
  36.         SPHIGS: 0.9
  37.  
  38. For full information on known bugs and omissions in these versions, and
  39. differences with the textbook's description, please read section 0 of the
  40. srgp.doc and sphigs.doc reference manuals.
  41.  
  42. SPHIGS v0.9 corrects the many compilation problems present in the original
  43. shipment (v0.8).  Mr. Sklar wishes to thank the many users who contributed
  44. information and source code leading to this new version, especially the
  45. Ross family (Hugh and Ann).  A list of the changes in SPHIGS source from v0.8
  46. to v0.9 is found in the "changes.doc" file described below.
  47.  
  48. You should be able to use either of these language platforms to run SRGP
  49. and SPHIGS applications:
  50.     *) Turbo C v2.0
  51.     *) Turbo C++ v1.0
  52.  
  53. ****************************************************************
  54. HOWEVER, if you wish to tinker with the source to SPHIGS, note that
  55. THE SPHIGS LIBRARY CAN ONLY BE MADE WITH THIS LANGUAGE PLATFORM:
  56.     *) Turbo C v2.0
  57. ****************************************************************
  58.  
  59. Moreover, use of the integrated-environment compiler (TC) is NOT desirable;
  60. use the command-line compiler (TCC).
  61.  
  62.   ==========================================================================
  63.                 ABOUT THE FILES
  64.  
  65.  
  66.     \README            This file!
  67.  
  68.     \SRGP\SRGP.LIB        The Turbo C library with which you must link
  69.                 in order to use SRGP
  70.     \SRGP\SRGP.H        The header file that you must include at the
  71.                 top of your SRGP application
  72.     \SRGP\SRGPPUBL.H    Header files included by SRGP.H
  73.     \SRGP\SRGP_SPH.H
  74.     \SRGP\SRGP_COM.H
  75.     \SRGP\GEOM.H        The header file for the small set of geometric
  76.                 utilities
  77.                 included in the SRGP library.
  78.     \SRGP\*.FNT        The MetaGraphics font files for use with an
  79.                 SRGP application
  80.  
  81.     \SRGPDOC\SRGP.DOC    A text file which is a terse but complete
  82.                 description of SRGP
  83.     \SRGPDOC\COLORS.DOC    A list of the "common colors" available to
  84.                 the routine SRGP_loadCommonColor()
  85.  
  86.     \METASHEL.EXE        MetaGraphics TSR program needed to run
  87.                 SRGP/PC applications
  88.  
  89.     \SRGPDEMO\README    About the demo programs provided in the
  90.                 SRGPDEMO directory.
  91.  
  92.     \SPHIGS\*.H        Header files needed for the creation of
  93.                 SPHIGS applications
  94.     \SPHIGS\SPHIGS.LIB    The Turbo C library with which you must link
  95.                 in order to use SPHIGS
  96.  
  97.     \SPHSRC\*.[CH]        Header and source files needed to create the
  98.                 SPHIGS library (in case you wish to make
  99.                 modifications to SPHIGS)
  100.     \SPHSRC\MAKEFILE    Help in creating the object files
  101.     \SPHSRC\BUILDLIB.BAT    A batch file you can use to create SPHIGS.LIB
  102.     \SPHSRC\OBJLIST.RSP    A file used by "tlib"... to create SPHIGS.LIB
  103.  
  104.     \SPHDOC\SPHIGS.DOC    A text file which is a terse but complete
  105.                 description of SPHIGS
  106.  
  107.     \SPHDEMO\README        About the demo program provided in the 
  108.                 SPHDEMO directory
  109.     \SPHDEMO\*.[CH]        Source code for the SPHDEMO program
  110.     \SPHDEMO\MAKEFILE    Help in creating the SPHDEMO program
  111.  
  112.  
  113.  
  114.  =============================================================================
  115.                                    FEEDBACK
  116.  
  117. Please send bug reports and suggestions for improvement (of both the software
  118. and the documentation) to:
  119.                         Graphics Textbook Support
  120.                         c/o Dr. van Dam
  121.                         Brown University box 1910
  122.                         Providence, RI  02912
  123.  
  124. If you have email available, you can send mail to "graphtext@cs.brown.edu".
  125. Please put the phrase "Report-Software-Bug" in the Subject line.
  126.  
  127.   ===========================================================================
  128.  
  129.                GENERAL INFORMATION ABOUT SRGP/PC
  130.  
  131. Currently SRGP/PC does not support the following (see the reference manual
  132. for details):
  133.     * plane masking
  134.     * XOR write mode for transparent bitmap patterns and text
  135.     * application control of table sizes
  136.  
  137. *** Warning ***
  138.     NOTE: all SRGP applications MUST call SRGP_end before terminating!
  139. Otherwise, your system will hang and require rebooting.
  140.  
  141. *** Mice ***
  142.     SRGP attempts to detect whether you have a mouse installed on your
  143. system. If it detects that you do not, it stops with an appropriate error
  144. message.  However, to SRGP modems or any serial port may look like a serial
  145. mouse; therefore SRGP may think you have a mouse when you do not.  As a result,
  146. it is VERY important to have your mouse driver running before you attempt to
  147. invoke an SRGP application. If you do not, your system will hang!
  148.  
  149. *** Fonts ***
  150.     Two fonts (in various sizes) are provided in the directory \SRGP: one
  151. called "system" and another called "extsys".  You may load any of these fonts
  152. by calling SRGP_loadFont(); for instance, SRGP_loadFont("system00") loads the
  153. font stored in SYSTEM00.FNT.  SRGP attempt to find the font file by looking in
  154. (1) the current directory, (2) a directory called \METAWNDO (if it exists), and
  155. (3) the directory \SRGP (if it exists).  If it can't find it in any of these
  156. places, an error message is sent to your logfile, if you are tracing; the
  157. program continues to use the current font.
  158.     NOTE: SRGP uses SYSTEM08.FNT by default.  Do not erase this font from
  159. your disk or move it somewhere SRGP can't find it!  If you do, SRGP will
  160. terminate with an appropriate error message.
  161.     NOTE: The two-digit number on each font file's name has no meaning;
  162. it does not tell you anything about the font's size.
  163.  
  164. *** Colors ***
  165.     Because it is compatible with color workstations running X11 and color
  166. Macintoshes, PC-SRGP was designed with VGA cards in mind, since only VGA cards
  167. have the same concept of a LUT table in which colors are stored.  Monochrome
  168. cards are similarly well supported.  However CGA cards are admittedly not well
  169. supported because their concept of color is very different.
  170.     CGA cards use several hard-wired palettes from which to select hard-
  171. wired colors rather than having a color table to store arbitrary colors like
  172. EGA/VGA cards do. As a result, PC-SRGP uses the CGA card's palette 0 and calls
  173. to SRGP_loadColorTable() and SRGP_loadCommonColor() have no effect.
  174.  
  175.  
  176. ==============================================================================
  177.  
  178.         GENERAL INFORMATION ABOUT SPHIGS/PC
  179.  
  180. SPHIGS applications are also SRGP applications; the SPHIGS package calls
  181. SRGP to perform all its graphics operations.  Therefore, the same graphics 
  182. limitations listed in the above section also apply to SPHIGS.
  183.  
  184. SPHIGS is heavily dependent upon floating-point operations; thus, it will be
  185. quite sluggish on machines that do not have floating-point accelerator chips.
  186. If you are planning to use SPHIGS as an aid for learning about PHIGS and
  187. about modeling in general, you'll be satisfied without an accelerator;
  188. but if your intention is more serious, involving research or professional work,
  189. you should consider enhancing your hardware with an accelerator.
  190.  
  191.  
  192. ==============================================================================
  193.  
  194.        GENERAL INFORMATION ON WRITING SRGP APPLICATIONS IN TURBO C
  195.  
  196. NOTE: This information is no substitute for:
  197.     1) Reading the "SRGP for Turbo C" reference manual
  198.     2) Being literate in ANSI C
  199.     3) Having access to Chapter 2 of the Foley, et.al. textbook
  200.     4) Having access to the Turbo C manuals
  201.  
  202. Section "0" of the "SRGP for TURBO C" documentation is very important.  It
  203. tells you about current shortcomings and omissions in the current version of
  204. SRGP/PC, and differences between SRGP/PC and the SRGP spec in the textbook.
  205.  
  206. In order to compile inside Turbo C's integrated environment, you must create
  207. a "project file" for your application.  This file consists of your applications
  208. files followed by the SRGP library.  Example: if my application, FOO.C, uses
  209. routines in UTIL.C as well as SRGP routines, my project file would contain the
  210. following three lines:
  211.  
  212.         FOO.C
  213.         UTIL.C
  214.         \SRGP\SRGP.LIB
  215.  
  216. Note that an abosolute path must be given for each file. Please see your Turbo
  217. C reference manual for more details on project files, as well as the project
  218. file for the examples on your disk.
  219.     Before compiling make sure that the Options/Directories menu is set up
  220. properly to point to all the necessary include and library files. Not doing so
  221. will result in compilation errors starting with one stating "file xxxx not
  222. found."
  223.  
  224.     IMPORTANT: The object files in the SRGP library were compiled using the
  225. LARGE memory model. Not compiling your application with the LARGE model will
  226. cause link errors.
  227.     Also note that by default Turbo C's own graphics library is linked in.
  228. With SRGP, this is unnecessary and may make your executable file unnecessarily
  229. larger.  To turn this off, look under the Options/Linker menu and turn the
  230. "Graphics library" choice off.
  231.  
  232.  
  233. ==============================================================================
  234.  
  235.      GENERAL INFORMATION ON WRITING SPHIGS/PC APPLICATIONS IN TURBO C
  236.  
  237. Section "0" of the "SPHIGS for ANSI-C" document is very important.  It tells
  238. you about current omissions in the current version of SPHIGS/PC, and
  239. differences between SPHIGS/PC and the SPHIGS spec in the textbook.
  240.  
  241. Before writing an SPHIGS/PC application, you must create the SPHIGS.LIB file.
  242. Create a TURBO C project that contains all the .c source files found in 
  243. \SPHSRC.  Compile that project into a .LIB file.  Of course, you only need
  244. perform this operation once.
  245.  
  246. Some users may wish to create two different projects (one called "MAT" and
  247. one called "SPHIGS") to create two different libraries ("MAT.LIB" and 
  248. "SPHIGS.LIB").  The former would contain the .c files whose names begin 
  249. with "MAT".  This is useful if, on your system, it is advisable to keep down
  250. the sizes of libraries.
  251.  
  252. Once you have created the MAT and SPHIGS libraries, you can begin writing
  253. SPHIGS applications.  The project file should contain your application's
  254. source files as well as:
  255.     \SRGP\SRGP.LIB
  256.     MAT.LIB
  257.     SPHIGS.LIB
  258.  
  259. Again, you must use the LARGE memory model, and you should turn the "Graphics
  260. library" choice off.
  261.  
  262.  
  263. ==============================================================================
  264.  
  265.             RUNNING YOUR SRGP/SPHIGS APPLICATION
  266.  
  267.     Once your program is successfully compiled, you must run your
  268. application by passing it to the program METASHEL.EXE. Example: I just compiled
  269. the FOO project to create FOO.EXE.  To run FOO.EXE, I type this:
  270.  
  271.     A:> METASHEL FOO
  272.  
  273. This is different from running most applications: you usually run an
  274. application by simply typing in its name at the DOS prompt.  If you run an
  275. SRGP/SPHIGS program using the "old" way, your system will hang!  Beware!
  276.  
  277. Obviously, this method makes it impossible to run your program from within
  278. the Turbo C integrated environment.
  279.  
  280. If you find the system hangs or is in a strange state after an SRGP/SPHIGS
  281. application finishes, it probably is the case that the application fails
  282. to call SRGP_end() before terminating.  Fix the source code if that's the case.
  283.  
  284. For advanced users: The metashel program can be installed as a TSR.  Use
  285. "metashel /i" to install, and "metashel /k" to remove.  We do not recommend
  286. running Turbo C while the TSR is installed.
  287.  
  288. -------------------------------------------------------------------------------
  289. -------------------------------------------------------------------------------
  290. -------------------------------------------------------------------------------
  291.